build: publish @cardstack/bxl to npm from the monorepo - #5810

@cardstack/bxl has an npm identity but nothing has ever gone out under it — the library was consumed as a per-realm bundle, and since the port it has been a workspace package only. This wires up publishing from the monorepo, following boxel-cli's shape: a conventional-commit PR title decides the version, merging publishes a prerelease, and cutting a stable release stays a deliberate act.

The artifact can't be the sources

The package's exports map points at src/*.ts, which works for both in-repo consumers — the host bundles the TypeScript, and the realm-server reaches it through the pnpm workspace link, whose realpath sits outside node_modules so Node type-strips it. An installed package lands inside node_modules, where Node refuses to strip types (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). Published as-is, the package would be dead on arrival.

So pnpm build (scripts/build.ts) emits JavaScript plus declarations and source maps into dist/, and publishConfig.exports points the published package there while the ordinary map keeps pointing at src/ — pnpm swaps the map in the tarball only, so nothing about local development changes. prepack runs the build, so no pack or publish can ship a stale or missing dist/. The tarball carries dist/ and src/ both: the maps resolve to real TypeScript, and NOTICE.md's attribution references into src/ stay valid.

Two things the compiler leaves behind, which the build fixes and then asserts:

• rewriteRelativeImportExtensions rewrites ./x.ts → ./x.js in emitted JavaScript (dynamic imports included, so the lazy formula chunks resolve) but not in declarations. The build rewrites those through the parsed syntax tree, so a .ts path in a doc comment isn't touched. TypeScript itself copes with a .ts specifier by substituting the sibling .d.ts — this is about the declarations describing the tree that actually shipped.
• The three /// <reference path="…/types/*.d.ts" /> shims for the untyped bessel / jstat / validator packages get copied into the emitted JavaScript, where the path resolves to nothing. They're blanked rather than deleted so source-map line numbering still lines up.

The build then refuses to finish if the two exports maps describe different subpaths, if a published target doesn't exist, or if anything in dist/ still names a .ts file.

Verifying the thing we ship

Every existing suite reads src/, so none of them says anything about the tarball. pnpm verify:package packs it, installs it with npm into a throwaway project outside the monorepo (npm, not pnpm, for the hoisted layout a consumer gets), and checks it from there: every subpath in the published exports map loads under plain Node, a formula evaluates end to end, a lazy chunk resolves, the TextMate grammar reads as JSON, the version the build reports matches the manifest, and a consumer's compiler — nodenext, strict, skipLibCheck off — resolves declarations across the whole surface. It runs pre-merge in the BXL CI job and again against the registry after each publish.

I confirmed that last check has teeth by deleting one declaration from an install: 9 errors. It does not catch the .ts-specifier form (TypeScript's substitution absorbs that) — the build's own assertion is what enforces it, and the comments say so rather than claiming otherwise.

When a merge publishes

scripts/compute-release.ts needs both a bumpable prefix and a change to something the tarball ships. A fix: touching only test suites, benchmarks, or the lint rules publishes nothing — no version burned on an artifact that didn't move. Already on a prerelease, the base is the accumulation since the last stable tag, so three fixes in a row give .0, .1, .2 of one patch version rather than three patch versions, and a later feat: escalates the base. Counters come from npm rather than git, since the manual publish path deliberately doesn't commit its bump. tests/unit/release-cli.ts covers those decisions — 65 checks, no git or npm involved.

The version lives in two places: package.json and VERSION in src/index.ts, which is what a consumer reads through BXL_BUILD_INFO. scripts/set-version.ts is the only thing that sets it and sets both; the build-info suite fails on drift; and the published-artifact check asserts the shipped package agrees with itself.

Promoting to stable (confirm = promote) strips the suffix, closes out the CHANGELOG's [Unreleased] section under the new version, and uses that section as the release notes — so it stops rather than shipping a version heading with nothing under it.

When a merge does not publish

compute-release.ts needs a bumpable prefix and a change to something the tarball ships, so a fix: touching only test suites or CI config publishes nothing. Two inputs are deliberately not taken from the checked-out tree:

• The changed-file set comes from the push event, github.event.before..github.sha, not from the checkout's HEAD. The workflow checks out main, whose tip can already carry another release commit by the time a run reaches it — classifying that diff would silently skip the release.
• The stable base a prerelease series builds on comes from a tag. It only lives in the manifest until the first prerelease is committed, so the run that consumes that last copy tags it (bootstrapStableTag). Without this, every merge after the first publish had no base to bump and failed.

Concurrency is this package's own group with queue: max: a group keeps one pending run by default and cancels it when another arrives, which would discard a release nothing retries. The cross-workflow push race is handled where it happens instead of by serializing — the release commit is pushed before anything is tagged, and replayed onto main if an ordinary merge lands first.

The workspace catalog counts as shipped surface, since catalog: specifiers resolve into the published manifest — but only when the entries that moved are ones this package depends on.

Notes for review

• The first publish cannot come from CI. boxel-cli publishes by npm Trusted Publishing, not a token — the registry records _npmUser.trustedPublisher for @cardstack/boxel-cli@0.5.0, and there is no repo-level NPM_TOKEN. A trusted-publisher rule can only be added to a package that already exists, and @cardstack/bxl has never been published (404, absent from the 88 packages in the scope). So the first version goes out by hand — pnpm publish from packages/bxl, never npm publish, since pnpm is what resolves the catalog: specifiers — and the rule for bxl-publish.yml is registered after that. The publish steps no longer set NODE_AUTH_TOKEN: nothing maps it to a credential here (no .npmrc, no setup-node), and pnpm 11 does not read it.
• This PR's title is build:, so merging it publishes nothing. A bumpable prefix would have cut a version on merge, and that first automated publish has nothing to authenticate with yet — it would fail after committing the version bump and pushing two tags. build: classifies as no release, so the workflow runs and no-ops, and the first version goes out through the steps below.
• Open bxl PRs will show a failing title check until they carry a prefix. That's the gate doing its job, same as boxel-cli's.
• boxel-cli's workflow is untouched. Its own HEAD^ anchoring has the same moved-main exposure for back-to-back merges; that predates this PR and is left alone rather than changing another package's release behavior here.
• The skill and AGENTS.md section covering prefixes were boxel-cli-only and would have been wrong for bxl PRs, so they now cover both packages.

Publishing the first version

The package does not exist on npm yet, and a trusted-publisher rule can only be
attached to one that does — so the first version is published by hand, once.
Everything after it comes from the workflow.

The version to publish is 0.6.0, already committed here: the tree had
accumulated fourteen changelog entries since the port — two additions, four
behavior changes, four fixes, and two removals — so publishing it under the
0.5.1 the package carried would have described it by an entry written for
something else. [Unreleased] is closed out under ## [0.6.0] to match.

1. Merge this PR. Safe to do at any time: the build: title classifies the
   merge as no release, so the workflow runs and no-ops.

2. Publish from a clean main, not from a branch — npm should hold what
   main holds, and pnpm's publish-branch guard checks exactly this:

   git checkout main && git pull
   cd packages/bxl
   npm login --scope=@cardstack   # if not already logged in
   pnpm publish --access public

   pnpm publish, never npm publish — pnpm is what resolves the
   catalog: dependency specifiers to real ranges. npm would ship literal
   catalog: and every install would fail. prepack builds dist/ first. The
   registry will ask for your second factor.

3. Tag the release, so the tag names the commit that shipped:

   git tag -a bxl-v0.6.0 -m bxl-v0.6.0 && git push origin bxl-v0.6.0

   The workflow creates this tag itself if it is missing, but pointed at
   whatever main's tip is at that moment rather than at the release commit.

4. Register the trusted publisher: npmjs.com → @cardstack/bxl → Settings →
   Trusted Publisher → GitHub Actions, repo cardstack/boxel, workflow
   bxl-publish.yml. This is the same arrangement boxel-cli publishes under,
   and it is why both publish paths live in one workflow file.

From then on, a merge touching what the tarball ships publishes
0.6.x-unstable.<n> under the unstable dist-tag, with provenance and no
credential held anywhere. latest stays at 0.6.0 until someone runs the
workflow with confirm = promote.

Verification

70/70 BXL suites (84 checks on the release decisions, 14 on the published exports map), lint clean, verify:package green off a real pnpm pack — an 864K tarball whose manifest carries the derived exports map and the catalog: specifiers resolved to real ranges.

Both new workflow files, plus ci.yaml, validate against the official GitHub workflow schema — worth doing because bxl-publish.yml only triggers on main, so no PR check would catch a bad key in it.

The build's assertions were checked by mutation rather than by reading: swapping two exports targets, dropping src from files, and adding a subpath to one map only each fail with a specific message, while a doc comment mentioning a .ts path now builds clean (it previously failed, since the check was a text search).

The two red Host Tests shards are the documented create realm users Synapse-container flake — the step fails before any test runs, and nothing here touches that path.